package api.list;

import java.io.Serializable;

/**
 * @author Ann Raboschuk
 *
 */
public interface List<T> extends Cloneable, Serializable
{
   /**
    * Adds specified element to the beginning of the list.
    * 
    * @param element element to be added to list
    */
   public void addFirst(T element);
   
   /**
    * Adds specified element to the end of the list.
    * 
    * @param element element to be added to list
    */
   public void addLast(T element);
   
   /**
    * Adds element to the specified position of the list.
    * 
    * @param element element to be added to list
    * @param index position in which element is added
    */
   public void add(int index, T element);
   
   /**
    * Deletes the first element of the list.
    */
   public void deleteFirst();
   
   /**
    * Deletes the last element of the list.
    */
   public void deleteLast();
   
   /**
    * Deletes element of the list in the specified position.
    * 
    * @param index position of the element which will be deleted
    */
   public void delete(int index);
   
   /**
    * Returns the number of elements in the list.
    * 
    * @return number of elements in the list
    */
   public int size();
   
   /**
    * Gets the element of the list in the specified position.
    * 
    * @param index position of the element
    * @return element in the specified position
    */
   public T get(int index);
   
   /**
    *  Replaces the element at the specified position in the list with the specified element.
    * 
    * @param index position of the element
    * @param element element to replaced with  
    */
   public void set(int index, T element);
   
   /**
    * Returns an iterator over the elements in this list in proper sequence.
    * 
    * @return iterator of the list
    */
   public Iterator<T> iterator();
   
   /**
    * Sorts the list in ascending order.
    */
   public void sort();
   
   /**
    * Creates and returns a copy of this object.
    * @return copy of the list
    */
   public List<T> cloneList();
   
   /**
    * Removes all of the elements from the list.
    */
   public void clear();
   
   /**
    * Tests if this list has no elements.
    * @return true if this list has no elements; false otherwise.
    */
   public boolean isEmpty();
   
   /**
    * Returns a part of the list between fromIndex, inclusive, and toIndex, exclusive. 
    * @param fromIndex
    * @param toIndex
    * @return a part of the specified range within the list.
    */
   public List<T> sublist(int fromIndex, int toIndex); 
   
   /**
    * Returns true if this list contains the specified element.
    * 
    * @param element element to be checked for containment in this list.
    * @return true if this list contains the specified element.
    */
   public int contains(T element);
}
